Conversation
WalkthroughAdds a new documentation page describing how to configure OIDC field mapping to handle non-standard provider claims across Platform Versions 4.x (UI/YAML) and 3.x (CLI/JSON). Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (6)
docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md (6)
8-8: Rename for idiomatic phrasing.Use “Integrating Non‑standard OIDC Providers: Field Mapping” instead of “Docking …” to match common English usage in technical docs.
12-21: Tighten error section; fix formatting and punctuation.Unescape the quotes and end bullets with periods. Example:
-`Internal error occurred: failed to authenticate: missing email claim, not found \"email\" key` +`Internal error occurred: failed to authenticate: missing email claim, not found "email" key` -**Common error messages:** - -- missing "email" claim: Missing email field -- missing "email_verified" claim: Missing email verification field -- missing "name" claim: Missing name field +**Common error messages:** +- Missing "email" claim: email field not found. +- Missing "email_verified" claim: email verification field not found. +- Missing "name" claim: name field not found.
93-111: HTTPS in examples.Add a note that production issuers should use HTTPS; the http://127.0.0.1 example is for local testing only.
121-125: Add scope/ discovery checks to diagnostics.Augment with:
- Ensure the client requests appropriate scopes (e.g., openid, profile, email, groups if supported).
- Inspect
/.well-known/openid-configurationforclaims_supportedanduserinfo_endpoint.- Some providers (e.g., Azure AD/Entra, Okta) require adding custom claims or enabling group overage features for
groups.
33-33: Consistency: use “IdP” capitalization throughout.Standardize “IDP” → “IdP” across the doc.
57-63: Groups and phone mapping caveat.Note that:
groupsoften requires explicit scope or custom claims; very large group lists may be truncated or moved to graph APIs by some IdPs.phonevalues should be normalized (e.g., E.164) if the platform relies on them.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md
[grammar] ~18-~18: There might be a mistake here.
Context: ...ssing "email" claim: Missing email field - missing "email_verified" claim: Missing ...
(QB_NEW_EN)
[grammar] ~19-~19: There might be a mistake here.
Context: ... claim: Missing email verification field - missing "name" claim: Missing name field...
(QB_NEW_EN)
[grammar] ~24-~24: There might be a mistake here.
Context: ...issing name field ## Environment - 4.x - 3.x ## Resolution The platform provide...
(QB_NEW_EN)
[grammar] ~113-~113: There might be a mistake here.
Context: ...e": "Jane Doe" } ``` Required fields: - sub: Unique identifier of the user (requ...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...Unique identifier of the user (required) - email: User email (usually mandatory) - ...
(QB_NEW_EN)
[grammar] ~115-~115: There might be a mistake here.
Context: ... - email: User email (usually mandatory) - email_verified: Whether the email has be...
(QB_NEW_EN)
[grammar] ~116-~116: There might be a mistake here.
Context: ...il has been verified (usually mandatory) - name: User name ## Diagnostic Steps 1....
(QB_NEW_EN)
[style] ~117-~117: It’s more common nowadays to write this noun as one word.
Context: ...en verified (usually mandatory) - name: User name ## Diagnostic Steps 1. **Check the ID...
(RECOMMENDED_COMPOUNDS)
🔇 Additional comments (2)
docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md (2)
65-68: Verify and pin docs link to the exact supported minor version.Confirm 4.1 is the intended target for 4.x users, or update to the precise minor versions you support to avoid drift.
71-85: Verify decode/patch commands in a real cluster
The sandbox lacksbase64, so confirm these steps work end-to-end in your environment:# Decode current config kubectl get connector -n cpaas-system <connector-name> -o jsonpath='{.spec.config}' | base64 -d | jq . # After editing config.json, re-encode and patch ENCODED=$(base64 -w0 config.json) kubectl patch connector -n cpaas-system <connector-name> --type merge -p "{\"spec\":{\"config\":\"$ENCODED\"}}"Also clarify whether any controller or pod restart is required for the updated config to take effect.
| # If the Provider cannot provide the email_verified field, the email verification check can be skipped. | ||
| insecureSkipEmailVerified: true | ||
|
|
||
| # Use other fields as the display name; the default is the name field. | ||
| userNameKey: display_name | ||
|
|
||
| # If the provider's /.well-known/openid-configuration provides a userinfo_endpoint, the UserInfo endpoint query can be enabled. | ||
| getUserInfo: true | ||
|
|
||
| # Field Mapping Configuration | ||
| claimMapping: | ||
| # If the provider cannot provide the email field, 'sub' can be used as a substitute. | ||
| # In addition to the sub field, other fields that can uniquely represent a user globally may also be used. | ||
| # Default email | ||
| email: sub | ||
|
|
||
| # If the provider uses 'user_groups' instead of 'groups' | ||
| # Default groups | ||
| groups: user_groups | ||
|
|
||
| # If the provider uses 'mobile' instead of 'phone' | ||
| phone: mobile | ||
| ``` |
There was a problem hiding this comment.
Security risk: don’t default to skipping email verification; avoid mapping email to sub.
insecureSkipEmailVerified: trueweakens account‑linking protections. Recommend defaulting to false and documenting this as a last resort.- Mapping
email: submay break flows expecting a valid email format and can confuse users/notifications. Prefer a real email/UPN claim (e.g.,email,preferred_username,upn,mail) and only fall back tosubif the platform explicitly treats “email” as a generic unique identifier.
Proposed YAML tweaks:
spec:
config:
- # If the Provider cannot provide the email_verified field, the email verification check can be skipped.
- insecureSkipEmailVerified: true
+ # Avoid disabling verification unless the IdP truly cannot provide it and you accept the risk.
+ # insecureSkipEmailVerified: true
- userNameKey: display_name
+ # Prefer stable username claims commonly provided by IdPs.
+ userNameKey: preferred_username
# Field Mapping Configuration
claimMapping:
- # Default email
- email: sub
+ # Prefer a real email/UPN-like claim; only fall back to `sub` if your deployment treats this as a generic UID.
+ # Default email
+ email: preferred_username📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # If the Provider cannot provide the email_verified field, the email verification check can be skipped. | |
| insecureSkipEmailVerified: true | |
| # Use other fields as the display name; the default is the name field. | |
| userNameKey: display_name | |
| # If the provider's /.well-known/openid-configuration provides a userinfo_endpoint, the UserInfo endpoint query can be enabled. | |
| getUserInfo: true | |
| # Field Mapping Configuration | |
| claimMapping: | |
| # If the provider cannot provide the email field, 'sub' can be used as a substitute. | |
| # In addition to the sub field, other fields that can uniquely represent a user globally may also be used. | |
| # Default email | |
| email: sub | |
| # If the provider uses 'user_groups' instead of 'groups' | |
| # Default groups | |
| groups: user_groups | |
| # If the provider uses 'mobile' instead of 'phone' | |
| phone: mobile | |
| ``` | |
| spec: | |
| config: | |
| # Avoid disabling verification unless the IdP truly cannot provide it and you accept the risk. | |
| # insecureSkipEmailVerified: true | |
| # Prefer stable username claims commonly provided by IdPs. | |
| userNameKey: preferred_username | |
| # If the provider's /.well-known/openid-configuration provides a userinfo_endpoint, the UserInfo endpoint query can be enabled. | |
| getUserInfo: true | |
| # Field Mapping Configuration | |
| claimMapping: | |
| # Prefer a real email/UPN-like claim; only fall back to `sub` if your deployment treats this as a generic UID. | |
| # Default email | |
| email: preferred_username | |
| # If the provider uses 'user_groups' instead of 'groups' | |
| # Default groups | |
| groups: user_groups | |
| # If the provider uses 'mobile' instead of 'phone' | |
| phone: mobile |
🤖 Prompt for AI Agents
docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md around
lines 41 to 63: the snippet currently recommends insecureSkipEmailVerified: true
and mapping email: sub which is a security and UX risk; change the guidance to
recommend insecureSkipEmailVerified default to false and mark skipping email
verification as a last-resort option with an explicit warning, and update the
claimMapping guidance to prefer real email/UPN claims (email, mail,
preferred_username, upn) and only suggest using sub as a fallback for unique
identifier scenarios while warning that mapping sub to email can break workflows
and that implementations should validate email format before treating the value
as an address.
| **Required fields:** | ||
| - sub: Unique identifier of the user (required) | ||
| - email: User email (usually mandatory) | ||
| - email_verified: Whether the email has been verified (usually mandatory) | ||
| - name: User name | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Correct OIDC requirements vs. platform requirements.
OIDC requires ID Tokens to include iss, sub, aud, exp, and iat. Claims like email, email_verified, name are not required by the OIDC spec; they’re optional and depend on scopes/provider. Reframe as below to avoid misleading readers.
-**Required fields:**
-- sub: Unique identifier of the user (required)
-- email: User email (usually mandatory)
-- email_verified: Whether the email has been verified (usually mandatory)
-- name: User name
+**Standard required ID Token claims (per OIDC):**
+- iss, sub, aud, exp, iat
+
+**Common user identity claims (optional; scope-dependent):**
+- email, email_verified, name, preferred_username, groups
+
+**Platform-required claims (for this solution):**
+- A stable subject (sub) is required.
+- An email/username claim (e.g., email, preferred_username, upn) may be required by your configuration. Adjust claimMapping accordingly.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Required fields:** | |
| - sub: Unique identifier of the user (required) | |
| - email: User email (usually mandatory) | |
| - email_verified: Whether the email has been verified (usually mandatory) | |
| - name: User name | |
| **Standard required ID Token claims (per OIDC):** | |
| - iss, sub, aud, exp, iat | |
| **Common user identity claims (optional; scope-dependent):** | |
| - email, email_verified, name, preferred_username, groups | |
| **Platform-required claims (for this solution):** | |
| - A stable subject (sub) is required. | |
| - An email/username claim (e.g., email, preferred_username, upn) may be required by your configuration. Adjust claimMapping accordingly. |
🧰 Tools
🪛 LanguageTool
[grammar] ~113-~113: There might be a mistake here.
Context: ...e": "Jane Doe" } ``` Required fields: - sub: Unique identifier of the user (requ...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...Unique identifier of the user (required) - email: User email (usually mandatory) - ...
(QB_NEW_EN)
[grammar] ~115-~115: There might be a mistake here.
Context: ... - email: User email (usually mandatory) - email_verified: Whether the email has be...
(QB_NEW_EN)
[grammar] ~116-~116: There might be a mistake here.
Context: ...il has been verified (usually mandatory) - name: User name ## Diagnostic Steps 1....
(QB_NEW_EN)
[style] ~117-~117: It’s more common nowadays to write this noun as one word.
Context: ...en verified (usually mandatory) - name: User name ## Diagnostic Steps 1. **Check the ID...
(RECOMMENDED_COMPOUNDS)
🤖 Prompt for AI Agents
In docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md around
lines 113-118, the doc currently lists sub, email, email_verified, name as
"Required fields" which is incorrect per the OIDC spec; change the heading and
text to reflect that OIDC requires iss, sub, aud, exp, and iat in ID Tokens and
that email, email_verified, name are optional/conditional based on
scope/provider. Replace the "Required fields" heading with something like
"Common/Optional fields" or "Typical claims" and add a brief note listing the
actual required OIDC claims (iss, sub, aud, exp, iat) and stating that claims
such as email, email_verified, and name are not guaranteed unless requested via
appropriate scopes or provided by the IdP.
mysekai7
changed the title
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (7)
docs/en/solutions/OIDC_field_mapping_configuration.md (7)
14-14: Unescape quotes in inline error textThe backslashes will render literally inside inline code. Quotes don’t need escaping in Markdown code spans.
-`Internal error occurred: failed to authenticate: missing email claim, not found \"email\" key` +`Internal error occurred: failed to authenticate: missing email claim, not found "email" key`
20-23: Tighten and standardize the “Common error messages” bulletsUse backticks for claim names and consistent phrasing.
-- missing "email" claim: Missing email field -- missing "email_verified" claim: Missing email verification field -- missing "name" claim: Missing name field +- missing `email` claim — email field is absent +- missing `email_verified` claim — email verification field is absent +- missing `name` claim — name field is absent
54-58: Clarify risks of mapping email to subOverloading
- # Default email - email: sub + # Default email + # Caution: mapping `email` to a non-email (e.g., `sub`) may impact features that rely on a real email address. + # Prefer fixing the IdP to return `email` or retrieve it via UserInfo. If unavoidable, ensure uniqueness and + # communicate limitations to admins and users. + email: subWould the platform support a distinct “unique ID”/“login ID” key (separate from
63-65: Confirm default claim name for phoneOIDC standard uses
phone_number. If the platform’s default isphone, note the divergence explicitly to avoid confusion.- # If the provider uses 'mobile' instead of 'phone' - phone: mobile + # If the provider uses 'mobile' instead of the platform default (`phone`; OIDC standard: `phone_number`) + phone: mobile
67-67: Minor terminology consistency: IDP → IdP“Identity Provider” is commonly abbreviated “IdP”. Consider standardizing across the doc.
75-81: Make 3.x kubectl steps more actionableInclude -o yaml for inspection and name placeholder style for edit.
kubectl get connectors -n cpaas-system - -# Edit connector information -kubectl edit connector -n cpaas-system <connector name> +kubectl get connector -n cpaas-system <connector-name> -o yaml + +# Edit connector information +kubectl edit connector -n cpaas-system <connector-name>
39-65: YAML snippet looks good; add comment about partial snippet contextCall out that the snippet is a fragment and actual CR requires full metadata (apiVersion/kind/metadata) when applied via kubectl.
spec: config: # Other configurations + # Note: this is a fragment shown from the OIDC IdP CR. When applying via kubectl, include apiVersion/kind/metadata.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/en/solutions/OIDC_field_mapping_configuration.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/en/solutions/OIDC_field_mapping_configuration.md
[grammar] ~20-~20: There might be a mistake here.
Context: ...ssing "email" claim: Missing email field - missing "email_verified" claim: Missing ...
(QB_NEW_EN)
[grammar] ~21-~21: There might be a mistake here.
Context: ... claim: Missing email verification field - missing "name" claim: Missing name field...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ...issing name field ## Environment - 4.x - 3.x ## Resolution The platform provide...
(QB_NEW_EN)
🔇 Additional comments (3)
docs/en/solutions/OIDC_field_mapping_configuration.md (3)
35-35: Verify UI labels and path for 4.xUI terms can differ between minor versions (e.g., “Administration” vs “Administrator”, “Identity Providers” vs “IDP”). Please confirm exact labels for 4.1+ and 4.2+.
-1. Navigate to Administrator → Users → IDP → Click to enter OIDC integration details → Click Update on the right side of Actions → Switch to YAML view +1. Navigate to Administration → Users → Identity Providers → <Your OIDC> → Actions ▸ Update → Switch to YAML view
89-95: Nice root cause summaryClear and accurate explanation of why non-standard claims break parsing.
95-113: Good, realistic ID Token exampleRepresentative claims and formatting look correct.
| # If the Provider cannot provide the email_verified field, the email verification check can be skipped. | ||
| insecureSkipEmailVerified: true | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add a security warning for insecureSkipEmailVerified
Skipping email verification lowers identity assurance. Call this out prominently.
insecureSkipEmailVerified: true
+
+**Warning:** Only set `insecureSkipEmailVerified: true` for trusted, internal IdPs where email ownership is validated by policy. Otherwise prefer fixing the IdP claims or using `getUserInfo` to retrieve `email_verified`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # If the Provider cannot provide the email_verified field, the email verification check can be skipped. | |
| insecureSkipEmailVerified: true | |
| # If the Provider cannot provide the email_verified field, the email verification check can be skipped. | |
| insecureSkipEmailVerified: true | |
| **Warning:** Only set `insecureSkipEmailVerified: true` for trusted, internal IdPs where email ownership is validated by policy. Otherwise prefer fixing the IdP claims or using `getUserInfo` to retrieve `email_verified`. |
🤖 Prompt for AI Agents
In docs/en/solutions/OIDC_field_mapping_configuration.md around lines 43 to 45,
add a prominent security warning near the insecureSkipEmailVerified example
explaining that setting insecureSkipEmailVerified: true lowers identity
assurance and should only be used in controlled, non-production or legacy
scenarios; instruct readers to avoid it in production, prefer configuring the
Provider to supply email_verified or implement alternative verification flows,
and include an explicit caution about potential account takeover and compliance
risks.
| 2. Decode the value of the config field using Base64. | ||
|
|
||
| The configuration information of the Provider will be displayed in JSON format. At this point, you can update the configuration in the JSON according to the field configuration of version 4.x. Finally, encode the information in base64 and update it to the connector resource. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Provide concrete Base64 decode/encode commands and newline handling
Avoid common pitfalls with trailing newlines and line-wrapping.
-2. Decode the value of the config field using Base64.
-
-The configuration information of the Provider will be displayed in JSON format. At this point, you can update the configuration in the JSON according to the field configuration of version 4.x. Finally, encode the information in base64 and update it to the connector resource.
+2. Decode the `config` field (Base64), edit JSON, then re-encode:
+
+```bash
+# Decode to file
+kubectl get connector -n cpaas-system <connector-name> -o json \
+ | jq -r '.spec.config' | base64 -d > oidc-config.json
+
+# Edit JSON per 4.x field mappings
+$EDITOR oidc-config.json
+
+# Re-encode without line wraps and patch back
+ENCODED=$(base64 -w0 < oidc-config.json)
+kubectl patch connector -n cpaas-system <connector-name> --type merge -p "{\"spec\":{\"config\":\"$ENCODED\"}}"
+```🤖 Prompt for AI Agents
In docs/en/solutions/OIDC_field_mapping_configuration.md around lines 83-86, the
instructions are missing concrete Base64 decode/encode commands and newline
handling; update the doc to show exact shell steps: use kubectl to output the
connector JSON, extract the .spec.config with jq -r and base64 -d redirecting to
a file, edit the JSON, then re-encode without line-wrapping (base64 --wrap=0 or
base64 -w0) and patch the connector with kubectl patch using a JSON merge patch
(ensure proper quoting/escaping of the encoded string); also note the macOS
base64 flag difference and recommend verifying no trailing newline is introduced
when re-encoding.
| 1. **Check the ID Token content**: You can use an online JWT decoding tool (such as [https://jwt.io](https://jwt.io)) to view the actual content of the ID Token and understand which fields the OIDC service provides. | ||
|
|
||
| 2. **Consult the IDP provider**: To map the required fields, consult the IDP provider's operations personnel to determine which fields were provided during authorization. | ||
|
|
||
| 3. **Verify authentication flow**: Test the OIDC authentication process to identify specific missing claims in the error messages. No newline at end of file |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add caution: don’t paste live tokens into third‑party sites
Recommend local decoding to avoid leaking tokens.
-1. **Check the ID Token content**: You can use an online JWT decoding tool (such as [https://jwt.io](https://jwt.io)) to view the actual content of the ID Token and understand which fields the OIDC service provides.
+1. **Check the ID Token content**: Prefer local decoding to avoid exposing tokens to third parties. Example:
+
+```bash
+# ID token structure (header.payload.signature)
+cut -d. -f2 <<< "$ID_TOKEN" | base64 -d 2>/dev/null | jq .
+```
+If using an online tool (e.g., jwt.io), never paste production tokens.🤖 Prompt for AI Agents
In docs/en/solutions/OIDC_field_mapping_configuration.md around lines 117–121,
add a clear caution not to paste live/production ID Tokens into third‑party
sites and instead recommend decoding tokens locally; update the section to (1)
prepend a short warning statement discouraging use of online JWT tools with
production tokens, (2) advise performing local decoding using common CLI tools
by extracting the token payload, base64‑decoding it, and pretty‑printing with
jq, and (3) include a fenced code block showing an example local decode command
and a note to redact or use non‑production tokens when using any online decoder.
* add docing not standard tpl * add docking non standard oidc * estructure OIDC field mapping solution documentation --------- Co-authored-by: root <chaowang1@alauda.io>
2 participants
Add solution for docking non-standard oidc
Summary by CodeRabbit